Object Handling (ODUtils)(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook / Part - Appendixes: Appendix A - OpenDoc Utilities

Object Handling (ODUtils)
This section describes the object-handling utilities defined in the files ODUtils.h and ODUtils.cpp. These utilities are useful for handling OpenDoc objects, especially reference-counted objects.

ODDeleteObject
The ODDeleteObject macro deletes an object, which can be a SOM object or another type of object (such as a C++ object), and sets the variable pointing to it to kODNULL. This macro takes one parameter, which points to the object, as follows:
ODDeleteObject(object)
ODReleaseObject
The ODReleaseObject macro releases (instead of deleting) a reference-counted SOM object and sets the variable pointing to it to kODNULL. This macro takes parameters pointing to the SOM environment structure and the object, as follows:
ODReleaseObject(ev, object)
ODFinalReleaseObject
The ODFinalReleaseObject macro is similar to ODReleaseObject, but it is meant to be used to release the last reference to a reference-counted object. It asserts that the object's reference count is equal to 1 before calling its Release method. This macro takes parameters pointing to the SOM environment structure and the object, as follows:
ODFinalReleaseObject(ev, object)
ODAcquireObject
The ODAcquireObject function increments the reference count of an object by 1 unless the object pointer passed into the function is kODNULL. The prototype of this function appears as follows:
void ODAcquireObject(Environment* ev, ODRefCntObject* object);
ODSafeReleaseObject
The ODSafeReleaseObject function releases a reference-counted object but requires no environment parameter. This function will not throw an exception. It is designed to be used in destructors, CATCH_ALL exception handling blocks, and somUninit methods where no pointer to the environment structure is available. The prototype of this function appears as follows:
void ODSafeReleaseObject(ODRefCntObject* object);
ODTransferReference
The ODTransferReference function decrements one object's reference count while incrementing another object's reference count. It is designed to be used in situations such as when using setter methods where you need to acquire a reference to one object while simultaneously releasing another.
This function ensures that the parameters do not point to the same object and that neither is null. It is possible for this function to throw an exception in the unlikely case that the Acquire or Release method call fails. The prototype of this function appears as follows:
void ODTransferReference( Environment*, ODRefCntObject* oldObj,
                              ODRefCntObject* newObj );
ODCopyAndRelease
The ODCopyAndRelease function returns a pointer to a copy of an object and releases the original object. This function is overloaded: one form takes and returns pointers to ODShape objects; the other takes and returns pointers to ODTransform objects. This function is designed to transfer control of an object to the caller, giving the caller permission to modify the object.
If the reference count of the original object is 1, the function is optimized simply to return a pointer to the original object, thereby avoiding the unnecessary expense of copying it. It is possible for this function to throw an exception in the unlikely case that the GetRefCount or Release method call fails. The prototypes of this function appear as follows:
ODShape* ODCopyAndRelease(Environment* ev, ODShape* shape);
ODTransform* ODCopyAndRelease(Environment* ev, ODTransform* transform);
ODObjectsAreEqual
The ODObjectsAreEqual function returns kODTrue if both ODObject pointers passed as parameters are not null and point to the same object.

IMPORTANT
Simply comparing the values of the pointers (as in the expression a==b) is not sufficient in the presence of distributed objects. Two pointers to the same remote object may have different numeric values.
The prototype of the ODObjectsAreEqual function appears as follows:
ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b);